<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <title>
Bugzilla::Token</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <link rel="stylesheet" title="style" type="text/css" href=".././../../../style.css" media="all" >

</head>
  <body id="pod">
<p class="backlinktop"><b><a name="___top" href="../index.html" accesskey="1" title="All Documents">&lt;&lt;</a></b></p>
<h1>Bugzilla::Token</h1>
<div class='indexgroup'>
<ul   class='indexList indexList1'>
  <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
  <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
  <li class='indexItem indexItem1'><a href='#SUBROUTINES'>SUBROUTINES</a>
  <ul   class='indexList indexList2'>
    <li class='indexItem indexItem2'><a href='#Security_related_routines'>Security related routines</a>
  </ul>
</ul>
</div>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>

<p>Bugzilla::Token - Provides different routines to manage tokens.</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>

<pre  class="code">    use Bugzilla::Token;

    Bugzilla::Token::issue_new_user_account_token($login_name);
    Bugzilla::Token::IssueEmailChangeToken($user, $old_email, $new_email);
    Bugzilla::Token::IssuePasswordToken($user);
    Bugzilla::Token::DeletePasswordTokens($user_id, $reason);
    Bugzilla::Token::Cancel($token, $cancelaction, $vars);

    Bugzilla::Token::CleanTokenTable();

    my $token = issue_session_token($event);
    check_token_data($token, $event)
    delete_token($token);

    my $token = Bugzilla::Token::GenerateUniqueToken($table, $column);
    my $token = Bugzilla::Token::HasEmailChangeToken($user_id);
    my ($token, $date, $data) = Bugzilla::Token::GetTokenData($token);</pre>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="SUBROUTINES"
>SUBROUTINES</a></h1>

<dl>
<dt><a name="issue_new_user_account_token($login_name)"
><code  class="code">issue_new_user_account_token($login_name)</code></a></dt>

<dd>
<pre  class="code"> Description: Creates and sends a token per email to the email address
              requesting a new user account. It doesn&#39;t check whether
              the user account already exists. The user will have to
              use this token to confirm the creation of his user account.

 Params:      $login_name - The new login name requested by the user.

 Returns:     Nothing. It throws an error if the same user made the same
              request in the last few minutes.</pre>

<dt><a name="sub_IssueEmailChangeToken($user,_$old_email,_$new_email)"
><code  class="code">sub IssueEmailChangeToken($user, $old_email, $new_email)</code></a></dt>

<dd>
<pre  class="code"> Description: Sends two distinct tokens per email to the old and new email
              addresses to confirm the email address change for the given
              user. These tokens remain valid for the next MAX_TOKEN_AGE days.

 Params:      $user      - User object of the user requesting a new
                           email address.
              $old_email - The current (old) email address of the user.
              $new_email - The new email address of the user.

 Returns:     Nothing.</pre>

<dt><a name="IssuePasswordToken($user)"
><code  class="code">IssuePasswordToken($user)</code></a></dt>

<dd>
<pre  class="code"> Description: Sends a token per email to the given user. This token
              can be used to change the password (e.g. in case the user
              cannot remember his password and wishes to enter a new one).

 Params:      $user - User object of the user requesting a new password.

 Returns:     Nothing. It throws an error if the same user made the same
              request in the last few minutes.</pre>

<dt><a name="CleanTokenTable()"
><code  class="code">CleanTokenTable()</code></a></dt>

<dd>
<pre  class="code"> Description: Removes all tokens older than MAX_TOKEN_AGE days from the DB.
              This means that these tokens will now be considered as invalid.

 Params:      None.

 Returns:     Nothing.</pre>

<dt><a name="GenerateUniqueToken($table,_$column)"
><code  class="code">GenerateUniqueToken($table, $column)</code></a></dt>

<dd>
<pre  class="code"> Description: Generates and returns a unique token. This token is unique
              in the $column of the $table. This token is NOT stored in the DB.

 Params:      $table (optional): The table to look at (default: tokens).
              $column (optional): The column to look at for uniqueness (default: token).

 Returns:     A token which is unique in $column.</pre>

<dt><a name="Cancel($token,_$cancelaction,_$vars)"
><code  class="code">Cancel($token, $cancelaction, $vars)</code></a></dt>

<dd>
<pre  class="code"> Description: Invalidates an existing token, generally when the token is used
              for an action which is not the one expected. An email is sent
              to the user who originally requested this token to inform him
              that this token has been invalidated (e.g. because an hacker
              tried to use this token for some malicious action).

 Params:      $token:        The token to invalidate.
              $cancelaction: The reason why this token is invalidated.
              $vars:         Some additional information about this action.

 Returns:     Nothing.</pre>

<dt><a name="DeletePasswordTokens($user_id,_$reason)"
><code  class="code">DeletePasswordTokens($user_id, $reason)</code></a></dt>

<dd>
<pre  class="code"> Description: Cancels all password tokens for the given user. Emails are sent
              to the user to inform him about this action.

 Params:      $user_id: The user ID of the user account whose password tokens
                        are canceled.
              $reason:  The reason why these tokens are canceled.

 Returns:     Nothing.</pre>

<dt><a name="HasEmailChangeToken($user_id)"
><code  class="code">HasEmailChangeToken($user_id)</code></a></dt>

<dd>
<pre  class="code"> Description: Returns any existing token currently used for an email change
              for the given user.

 Params:      $user_id - A user ID.

 Returns:     A token if it exists, else undef.</pre>

<dt><a name="GetTokenData($token)"
><code  class="code">GetTokenData($token)</code></a></dt>

<dd>
<pre  class="code"> Description: Returns all stored data for the given token.

 Params:      $token - A valid token.

 Returns:     The user ID, the date and time when the token was created and
              the (event)data stored with that token.</pre>
</dd>
</dl>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Security_related_routines"
>Security related routines</a></h2>

<p>The following routines have been written to be used together as described below, although they can be used separately.</p>

<dl>
<dt><a name="issue_session_token($event)"
><code  class="code">issue_session_token($event)</code></a></dt>

<dd>
<pre  class="code"> Description: Creates and returns a token used internally.

 Params:      $event - The event which needs to be stored in the DB for future
                       reference/checks.

 Returns:     A unique token.</pre>

<dt><a name="check_token_data($token,_$event)"
><code  class="code">check_token_data($token, $event)</code></a></dt>

<dd>
<pre  class="code"> Description: Makes sure the $token has been created by the currently logged in
              user and to be used for the given $event. If this token is used for
              an unexpected action (i.e. $event doesn&#39;t match the information stored
              with the token), a warning is displayed asking whether the user really
              wants to continue. On success, it returns 1.
              This is the routine to use for security checks, combined with
              issue_session_token() and delete_token() as follows:

              1. First, create a token for some coming action.
              my $token = issue_session_token($action);
              2. Some time later, it&#39;s time to make sure that the expected action
                 is going to be executed, and by the expected user.
              check_token_data($token, $action);
              3. The check has been done and we no longer need this token.
              delete_token($token);

 Params:      $token - The token used for security checks.
              $event - The expected event to be run.

 Returns:     1 on success, else a warning is thrown.</pre>

<dt><a name="delete_token($token)"
><code  class="code">delete_token($token)</code></a></dt>

<dd>
<pre  class="code"> Description: Deletes the specified token. No notification is sent.

 Params:      $token - The token to delete.

 Returns:     Nothing.</pre>
</dd>
</dl>
<p class="backlinkbottom"><b><a name="___bottom" href="../index.html" title="All Documents">&lt;&lt;</a></b></p>

<!-- end doc -->

</body></html>
